Fixes #41

Summary

Training with a constant target-slack penalty weight either hides target violations (low/moderate weight:
the deterministic-equivalent view looks great while the stage-wise rollout violates its own targets) or
degrades the learned policy (high weight from epoch 1). This PR adds the penalty-schedule option proposed
in #41: a multiplier ladder ×0.1 → ×1 → ×10 → ×30 applied during training, relative to the penalty the
models were built with (so with penalty=:auto, relative to the auto-calibrated base
= max |objective coefficient|).

What changed

• src/utils.jl: default_annealed_schedule(num_batches) (phase lengths proportional to 2/2/4/16, every
  phase ≥ 1 batch, < 4 batches falls back to the tail of the ladder so runs always end at ×30), schedule
  validation (contiguous from batch 1, finite positive multipliers, past-end hold), and internal helpers
  that capture the objective coefficients of the norm_deficit variables once at training start and
  rescale them at phase boundaries. Scaling that single coefficient covers all three create_deficit!
  modes (L1-only, L2-only, and the combined mode where the L1/L2 weights live in the linking constraint),
  as well as the renamed copies inside deterministic-equivalent and shooting-window models — no model
  rebuild is needed.
• src/simulate_multistage.jl / src/multiple_shooting.jl: a new penalty_schedule keyword on both
  train_multistage overloads and on train_multiple_shooting. nothing (default) leaves behavior
  exactly as today; :default_annealed builds the ladder over num_batches; an explicit vector of
  (first_batch, last_batch, multiplier) phases is validated and used as given.
• examples/HydroPowerModels: the three trainers default to the annealed schedule. They now make a single
  training call spanning num_epochs*num_batches batches so the schedule covers the whole run. Deliberate
  example-behavior notes: this keeps one optimizer state for the whole run (previously Flux.setup re-ran
  every epoch, silently resetting Adam moments), makes a true return from the record callback stop the
  whole run (previously it only ended the current epoch), and drops the iter % 2100 batch-doubling hook
  (which the collapsed iteration count would have newly activated). Constant-penalty training remains
  available via penalty_schedule = nothing.
• test/runtests.jl: schedule-resolution exactness (including the 24-batch reference ladder
  1:2 ×0.1, 3:4 ×1, 5:8 ×10, 9:24 ×30), validation rejections, past-end hold, coefficient scaling in all
  three create_deficit! modes, untouched coefficients on the default path, and an end-to-end
  train_multistage run crossing a phase boundary on DiffOpt models.

Validation

• Pkg.test() green on this branch (210/210, includes the new testsets).
• Reduced-scale demo (Bolivia DCP, 12 stages, 240 batches per arm, vanilla Ipopt, identical seeds and a
  fixed 6-scenario held-out set): with the constant as-built penalty the trained policy ends at a
  stage-wise-rollout target-violation share of 0.220 — far outside the ≤ ~0.05 trust gate — while its
  deterministic-equivalent view looks unremarkable; with the annealed default at the same budget the share
  drops to 0.052 — near but still slightly above the ≤ ~0.05 gate (4.2× lower). This is partial,
  reduced-scale evidence for the core mechanism of the issue (constant penalties learn targets that are
  not followable stage by stage; annealing restores followability); it is not reduced-scale gap closure.
  The full gap-closure endpoint of the issue table (det-eq ≡ rollout to ~1e-7 relative) requires
  full-scale training and is documented in the issue itself.

Notes

• Library behavior is backward compatible: penalty_schedule=nothing is the default and the gated code
  path leaves every objective coefficient untouched. Only the examples change their default to annealed.
• The combined L1+L2 mode anneals both weights by the same multiplier (the ladder is a uniform multiplier
  by construction); annealing them separately is out of scope.
• Only default_annealed_schedule is exported; the capture/apply helpers are internal.
• Note: this PR and Target-penalty annealing: a constant slack-penalty weight either hides target violations or degrades the learned policy #41/Deterministic-equivalent evaluation can overstate policy quality — add a stage-wise rollout evaluation and a target-violation metric #42 both touch
  examples/HydroPowerModels/train_dr_hydropowermodels_subproblems.jl; whichever merges second will be
  rebased onto the other.